Rotacja kreacji reklamy za pomocą interfejsu Select URL API

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Aby określić, jaką kreację użytkownik widzi w różnych witrynach, użyj interfejsu Select URL API, który korzysta z Shared Storage.

Reklamodawca lub twórca treści może chcieć zastosować w kampanii różne strategie rotacji treści i rotować treści lub kreacje, aby zwiększyć skuteczność. Interfejs Select URL API umożliwia stosowanie różnych strategii rotacji, np. rotacji sekwencyjnej i równomiernej, w różnych witrynach.

Dzięki rotacji kreacji w Select URL API możesz przechowywać dane, takie jak identyfikator kreacji, liczba wyświetleń i interakcje użytkowników, aby określać, które kreacje widzą użytkownicy w różnych witrynach.

Więcej informacji o interfejsie API i sposobie działania wyboru znajdziesz w dokumentacji interfejsu Select URL API.

Wypróbuj rotację kreacji

Aby przetestować rotację kreacji, upewnij się, że interfejs Select URL API i Shared Storage są włączone:

• W sekcji chrome://settings/content/siteData wybierz Allow sites to save data on your device lub Delete data sites have saved to your device when you close all windows.
• W sekcji chrome://settings/adPrivacy/sites kliknij Site-suggested ads.

Aby zobaczyć wersję demonstracyjną kodu z tego dokumentu, skorzystaj z demonstracji Shared Storage na żywo.

Demonstracja z przykładami kodu

W tym przykładzie:

• creative-rotation.js to skrypt zewnętrzny definiujący treści, które mają być wyświetlane naprzemiennie, wraz z danymi określającymi, które treści mają być wyświetlane jako następne, np. wagi w tym przykładzie. Skrypt jest wykonywany na stronie wydawcy. Ten skrypt wywołuje worklet Shared Storage, aby określić, które treści wyświetlić na podstawie dostępnych danych w magazynie i listy adresów URL, spośród których można wybierać.

• creative-rotation-worklet.js to element roboczy udostępnionego magazynu usługi innej firmy, który sprawdza strategię rotacji, oblicza, które treści należy opublikować jako następne, i zwraca te treści.

Jak działa wersja demonstracyjna

1. Gdy użytkownik odwiedza stronę wydawcy, wczytuje się skrypt zewnętrzny creative-rotation.js. Skrypt rotacji kreacji odpowiada za wczytywanie i uruchamianie workletu w wspólnym magazynie. Skrypt przekazuje wywołaniu workletu listę adresów URL do wyboru.
2. Jeśli w ramach elementu roboczego pamięć współdzielona nie została jeszcze zainicjowana, inicjuje się ona za pomocą początkowej strategii rotacji kreacji i indeksu kreacji. Początkowa strategia rotacji użyta w tym pokazie to strategia sekwencyjna.
3. Worklet odczytuje tryb rotacji z pamięci współdzielonej i zwróci indeks następnej reklamy. W przypadku trybu sekwencyjnego rotowania aktualizuje też indeks kreacji w wspólnym magazynie za pomocą nowej wartości, która zostanie użyta w następnym wywołaniu.Worklet zwraca obiekt FencedFrameConfig lub nieprzezroczysty obiekt URN na podstawie wartości resolveToConfig użytej podczas wywołania selectURL.
4. Skrypt rotacji kreacji wyświetla wybraną reklamę w ramce ograniczonej lub w ramce iframe. Szczegółowe informacje o typach danych zwracanych przez tę funkcję znajdziesz w dokumentacji dotyczącej renderowania dokumentu reklamy.
5. Gdy użytkownik zmieni tryb rotacji, moduł udostępniania w Shared Storage zaktualizuje wartość trybu rotacji kreacji przechowywaną w Shared Storage.
6. Po ponownym załadowaniu strony wydawcy powtarzają się kroki 1–4, co umożliwia wybranie następnej reklamy do wyświetlenia na podstawie wybranej strategii rotacji.

Przykładowe fragmenty kodu

Poniżej znajdziesz przykłady kodu dla plików creative-rotation.js i creative-rotation-worklet.js.

creative-rotation.js

const contentProducerUrl = 'https://your-server.example';

// Ad config with the URL of the ad, a probability weight for rotation, and the clickthrough rate.
const DEMO_AD_CONFIG = [
  {
    url: `${contentProducerUrl}/ads/ad-1.html`,
    weight: 0.7,
  },
  {
    url: `${contentProducerUrl}/ads/ad-2.html`,
    weight: 0.2,
  },
  {
    url: `${contentProducerUrl}/ads/ad-3.html`,
    weight: 0.1,
  },
];

async function setRotationMode(rotationMode) {
  // Load the worklet module
  const creativeRotationWorklet = await window.sharedStorage.createWorklet(
    `${contentProducerUrl}/url-selection/creative-rotation-worklet.js`,
    { dataOrigin: 'script-origin' }
  );

  await creativeRotationWorklet.run('set-rotation-mode', {
    data: { rotationMode }
  });
  console.log(`creative rotation mode set to ${rotationMode}`);
}

async function injectAd() {
  // Load the worklet module
  const creativeRotationWorklet = await window.sharedStorage.createWorklet(
    `${contentProducerUrl}/url-selection/creative-rotation-worklet.js`,
    { dataOrigin: 'script-origin' }
  );

  const urls = DEMO_AD_CONFIG.map(({ url }) => ({ url }));

  // Resolve the selectURL call to a fenced frame config only when it exists on the page
  const resolveToConfig = typeof window.FencedFrameConfig !== 'undefined';

  // Run the URL selection operation to determine the next ad that should be rendered
  const selectedUrl = await creativeRotationWorklet.selectURL('creative-rotation', urls, {
    data: DEMO_AD_CONFIG,
    resolveToConfig
  });

  const adSlot = document.getElementById('ad-slot');

  if (resolveToConfig && selectedUrl instanceof FencedFrameConfig) {
    adSlot.config = selectedUrl;
  } else {
    adSlot.src = selectedUrl;
  }
}

injectAd();

creative-rotation-worklet.js

class SelectURLOperation {
  async run(urls, data) {
    // Initially set the storage to sequential mode for the demo
    await SelectURLOperation.seedStorage();

    // Read the rotation mode from Shared Storage
    const rotationMode = await sharedStorage.get('creative-rotation-mode');

    // Generate a random number to be used for rotation
    const randomNumber = Math.random();

    let index;

    switch (rotationMode) {
      /**
       * Sequential rotation
       * - Rotates the creatives in order
       * - Example: A -> B -> C -> A ...
       */
      case 'sequential':
        const currentIndex = await sharedStorage.get('creative-rotation-index');
        index = parseInt(currentIndex, 10);
        const nextIndex = (index + 1) % urls.length;

        console.log(`index = ${index} / next index = ${nextIndex}`);

        await sharedStorage.set('creative-rotation-index', nextIndex.toString());
        break;

      /**
       * Evenly-distributed rotation
       * - Rotates the creatives with equal probability
       * - Example: A=33% / B=33% / C=33%
       */
      case 'even-distribution':
        index = Math.floor(randomNumber * urls.length);
        break;

      /**
       * Weighted rotation
       * - Rotates the creatives with weighted probability
       * - Example: A=70% / B=20% / C=10%
       */
      case 'weighted-distribution':
        console.log('data = ', JSON.stringify(data));
        // Find the first URL where the cumnulative sum of the weights
        // exceed the random number. The array is sorted by the weight
        // in descending order.
        let weightSum = 0;
        const { url } = data
          .sort((a, b) => b.weight - a.weight)
          .find(({ weight }) => {
            weightSum += weight;
            return weightSum > randomNumber;
          });

        index = urls.indexOf(url);
        break;

      default:
        index = 0;
    }

    console.log(JSON.stringify({ index, randomNumber, rotationMode }));
    return index;
  }

  // Set the mode to sequential and set the starting index to 0.
  static async seedStorage() {
    await sharedStorage.set('creative-rotation-mode', 'sequential', {
      ignoreIfPresent: true,
    });

    await sharedStorage.set('creative-rotation-index', 0, {
      ignoreIfPresent: true,
    });
  }
}

class SetRotationModeOperation {
  async run({ rotationMode }) {
    await sharedStorage.set('creative-rotation-mode', rotationMode);
  }
}

// Register the operation as 'creative-rotation'
register('creative-rotation', SelectURLOperation);
register('set-rotation-mode', SetRotationModeOperation);

Przewodnik ze zrzutami ekranu

1. Aby uzyskać dostęp do rotacji kreacji za pomocą interfejsu Select URL API i Shared Storage, otwórz stronę https://shared-storage-demo.web.app/. Wybierz demonstrację „Rotacja kreacji”.

2. Zapoznaj się z wersją demonstracyjną jako „Wydawca A”. Zostaniesz przekierowany na stronę https://shared-storage-demo-publisher-a.web.app/creative-rotation. Strona wczytuje treści o numerze na podstawie danych rotacji kreacji zapisanych w Shared Storage, do których uzyskuje się dostęp za pomocą interfejsu Select URL API. Tryby demonstracyjne rotacji kreacji to sekwencja, równomierna dystrybucja i dystrybucja z wagą. Worklet wykonuje logikę, aby wybrać treści, które mają się wyświetlać w ramce iframe. Na poniższym obrazku widać stronę wydawcy.

   
   

3. Aby wyświetlić zawartość Shared Storage, w Narzędziach programisty Chrome wybierz Aplikacja > Shared Storage. W przypadku pamięci współdzielonej tworzone są 2 elementy. Pusty magazyn jest dostępny dla pochodzenia https://shared-storage-demo-publisher-a.web.app. Będzie ono zawierać miejsce na dane związane z tą domeną i pozostanie puste w przypadku naszego demo, ponieważ wydawca nie musi zapisywać danych w wspólnym miejscu na dane. Pamiętaj, że gdy później odwiedzisz tę stronę w ramach demonstracji, dla wydawcy B zostanie utworzone podobne miejsce na dane.

   
   

4. Utworzymy kolejny wpis Shared Storage dla źródła https://shared-storage-demo-content-producer.web.app. To miejsce przechowywania elementu iframe zewnętrznego dostawcy, który jest umieszczony na stronie wydawcy. To miejsce na dane będzie służyć do udostępniania danych między 2 dostępnymi wydawcami w celu koordynacji wyboru kreacji. Ten wspólny magazyn będzie służył do zapisywania informacji o wyświetlanej kreacji i strategii rotacji za pomocą 2 par klucz-wartość. Pierwszym kluczem użytym w tym filmie jest creative-rotation-index, którego wartość to bieżący indeks kreacji w trybie sekwencyjnym. Drugim kluczem jest creative-rotation-mode, który określa używaną strategię rotacji.

   
   

5. Odświeżenie strony w trybie sekwencyjnym spowoduje wyświetlenie następnej kreacji w kolejności 1, 2, 3, 1, itd. Wartość klucza „creative-rotation-index” zmieni się zgodnie z indeksem wyświetlanej kreacji w trybie sekwencyjnym.

   
   

6. Zmiana trybu rotacji reklam za pomocą przycisków sterujących spowoduje zaktualizowanie wartości klucza „creative-rotation-mode” w odpowiedniej strategii. Kod workletu będzie go używać do wybierania kolejnej kreacji do wyświetlenia w elementzie iframe. Pamiętaj, że wartość zapisana w przypadku parametru creative-rotation-index nie zmienia się w przypadku innych trybów rotacji niż sekwencyjny.

   
   

7. Otwórz stronę „Publisher B” pod adresem https://shared-storage-demo-publisher-b.web.app/creative-rotation. W trybie sekwencyjnym wyświetlana kreacja powinna być kolejną kreacją w sekwencji wyświetlanej po odwiedzeniu adresu URL należącego do „Publisher A”. Po sprawdzeniu wspólnego miejsca na dane producenta treści można zauważyć, że zarówno „Wydawca A”, jak i „Wydawca B” korzystają z tego samego miejsca na dane i korzystają z tych samych ustawień do wybierania kolejnej kreacji do wyświetlenia oraz do określania strategii rotacji.

   
   

8. Pamięć współdzielona „Wydawcy B” jest pusta, podobnie jak pamięć współdzielona „Wydawcy A”.

   
   

   Przypadki użycia

   W tej sekcji znajdziesz wszystkie dostępne przypadki użycia interfejsu Select URL API. Będziemy dodawać kolejne przykłady, gdy będziemy otrzymywać opinie i odkrywać nowe przypadki testowe.

   • Rotacja kreacji reklamowych: przechowuj dane, takie jak identyfikator kreacji i interakcje użytkowników, aby określić, które kreacje wyświetlają się użytkownikom w różnych witrynach.
   • Wybieranie kreacji reklamowych według częstotliwości wyświetleń: na podstawie danych o liczbie wyświetleń możesz określić, które kreacje wyświetlają się użytkownikom w różnych witrynach.
   • Przeprowadzanie testów A/B: możesz przypisać użytkownika do grupy eksperymentalnej, a potem zapisać tę grupę w Shared Storage, aby umożliwić dostęp do niej w różnych witrynach.
   • Dostosowywanie interfejsu dla znanych klientów: udostępniaj treści i wezwania do działania na podstawie stanu rejestracji lub innych stanów użytkownika.

Angażowanie użytkowników i przesyłanie opinii

Pamiętaj, że interfejs Select URL API jest obecnie przedmiotem dyskusji i jest w trakcie opracowywania, dlatego może ulec zmianie.

Chętnie poznamy Twoją opinię na temat interfejsu Select URL API.

• Proponowana oferta: zapoznaj się ze szczegółami oferty.
• Dyskusja: dołącz do trwającej dyskusji, aby zadawać pytania i dzielić się swoimi spostrzeżeniami.

Trzymaj rękę na pulsie

• Lista mailingowa: zasubskrybuj naszą listę mailingową, aby otrzymywać najnowsze informacje i komunikaty dotyczące interfejsów Select URL i Shared Storage API.

Potrzebujesz pomocy?

• Pomoc dla deweloperów: możesz kontaktować się z innymi deweloperami i uzyskiwać odpowiedzi na swoje pytania w repozytorium pomocy dla deweloperów Piaskownicy prywatności.